feat: add `find` command for catalog search by nadavs123 · Pull Request #174 · microsoft/fabric-cli

nadavs123 · 2026-02-15T09:54:03Z

📥 Pull Request

Closes #172

Summary

Adds a new find command that searches for Fabric items across all accessible workspaces using the Catalog Search API (POST /v1/catalog/search).

Usage

# Basic search
fab find "sales report"

# Filter by item type(s)
fab find "data" --type Lakehouse
fab find "monthly" --type Report Warehouse

# Limit results
fab find "dashboard" --max-items 10

# Detailed view (shows IDs for scripting)
fab find "sales" -l

# Pagination
fab find --next-token "eyJTa2lwIjoy..."

Flags

Flag	Description
`--type`	Filter by item type(s), space-separated
`--max-items`	Maximum results per page (1-1000)
`-l`/`--long`	Show detailed output with IDs
`--next-token`	Continuation token for next page

Implementation details

Follows existing CLI patterns: @fab_command decorator, print_output_format(), FabricCLIError
Tab-completion for --type via argcomplete
--max-items validation (1-1000)
Structured error handling for unsupported/unknown types, missing query, API failures
Description column hidden in compact mode when no items have descriptions
Empty fields hidden in long (-l) mode
Pagination via --next-token (continuation token approach)

Files added

src/fabric_cli/client/fab_api_catalog.py — API client
src/fabric_cli/commands/find/__init__.py — Package init
src/fabric_cli/commands/find/fab_find.py — Command logic
src/fabric_cli/parsers/fab_find_parser.py — Argument parser
tests/test_commands/find/__init__.py — Test package init
tests/test_commands/find/test_find.py — 22 unit tests
.changes/unreleased/added-20260209-171617.yaml — Changie entry

Files modified

src/fabric_cli/core/fab_parser_setup.py — Register find parser

Notes

Dashboard is the only unsupported item type
Dataflow Gen1/Gen2 are currently not searchable; only Dataflow Gen2 CI/CD is returned (as type Dataflow)
Scorecards are returned as type Report
Requires Catalog.Read.All scope (not yet added to CLI app registration)

Features: - Search across all workspaces by displayName, workspaceName, or description - Filter by item type with --type flag - Limit results with --limit flag - Detailed output with --detailed flag (includes id, workspaceId) - Custom endpoint support with --endpoint flag or FAB_CATALOG_ENDPOINT env var Output columns (default): name, type, workspace, description Output columns (detailed): + workspaceId, id Required scope: Catalog.Read.All Unsupported types: Dashboard, Dataflow, Scorecard Includes unit tests (12 tests passing)

…dling Changes based on issue microsoft#172 feedback: - Changed --type from comma-separated to nargs='+' (space-separated) - Removed --endpoint flag (use internal mechanism instead) - Added FabricCLIError for invalid/unsupported item types - Added error handling for API failures - Updated tests to match new patterns (15 tests passing)

- Added complete_item_types() completer for searchable types - Tab completion excludes unsupported types (Dashboard, Dataflow, Scorecard) - Restored unsupported type validation with clear error message - Updated ALL_ITEM_TYPES list from official API spec - Added SEARCHABLE_ITEM_TYPES for valid filter types - 20 tests passing

- Keep tab-completion for --type flag - Custom FabricCLIError for unsupported types (Dashboard, Dataflow, Scorecard) - Custom FabricCLIError for unknown types - Cleaner error messages vs argparse choices listing all 40+ types - 22 tests passing

- Changed from data= to json= for request payload - Added raw_response=True to avoid auto-pagination hanging - Added fallback from displayName to name (API bug workaround) - Updated tests to use dict instead of JSON string - Successfully tested against dailyapi.fabric.microsoft.com

…, workspace_id, description)

…chable)

…ination and -P params - Interactive mode: pages 50 items at a time with 'Press any key to continue...' - Command-line mode: fetches up to 1000 items in a single request - Replace --type with -P type=Report,Lakehouse (key=value pattern) - Remove --max-items and --next-token flags Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The Catalog Search API returns an empty string continuationToken on the last page instead of null/omitting it. This caused the interactive pagination loop to send an empty token on the next request, which the API treats as a fresh empty search — returning unrelated results from the entire tenant. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Long descriptions caused the table separator line to wrap, appearing as a double separator. Descriptions are now truncated with ellipsis to keep the table within the terminal width. Full descriptions are still available via -l/--long mode. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Command-line mode now fetches all pages instead of stopping at one page of 1000. Uses the same continuation token pattern as interactive mode with 'or None' guard against empty string tokens. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Use contractions and active voice for friendlier tone - Suggest close matches for unknown types instead of dumping all 43 - Remove redundant type list from unsupported type error Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

aviatco · 2026-03-15T11:01:37Z

src/fabric_cli/commands/find/fab_find.py

+
+
+# All Fabric item types (from API spec, alphabetically sorted)
+ALL_ITEM_TYPES = [


Can't we have those types from an API and save it on init?
If not, please move it to separate file, maybe fab_constant or create type_supported.yaml - same as we have command_supported.

aviatco · 2026-03-15T11:03:20Z

src/fabric_cli/commands/find/fab_find.py

+]
+
+# Types that ARE searchable (for validation)
+SEARCHABLE_ITEM_TYPES = [t for t in ALL_ITEM_TYPES if t not in UNSUPPORTED_ITEM_TYPES]


why not having supported and unsupported type list?

aviatco · 2026-03-15T11:13:47Z

src/fabric_cli/commands/find/fab_find.py

+    if args.query:
+        args.query = utils.process_nargs(args.query)
+
+    is_interactive = getattr(args, "fab_mode", None) == fab_constant.FAB_MODE_INTERACTIVE


The current fab_mode check does not always indicate that the CLI is running in interactive mode. When the user runs fab and presses Enter, the CLI enters interactive mode even if the configuration mode is set to command_line. You may want to pass this explicitly to the command as a parameter.

aviatco · 2026-03-15T11:17:15Z

src/fabric_cli/client/fab_api_catalog.py

+from fabric_cli.client.fab_api_types import ApiResponse
+
+
+def catalog_search(args: Namespace, payload: dict) -> ApiResponse:


nit - since we are in catalog_api consider rename to search(args: Namespace, payload: dict)

aviatco · 2026-03-15T11:20:35Z

src/fabric_cli/commands/find/fab_find.py

+
+def _raise_on_error(response) -> None:
+    """Raise FabricCLIError if the API response indicates failure."""
+    if response.status_code != 200:


are we getting to this point?
since do_request() handle cases where status is not 200 and throw an error that is catch by handle_exceptions decorator

aviatco · 2026-03-15T13:04:39Z

src/fabric_cli/parsers/fab_find_parser.py

+        required=False,
+        metavar="",
+        nargs="*",
+        help="Parameters in key=value or key!=value format. Use brackets for multiple values: type=[Lakehouse,Notebook]. Use != to exclude: type!=Dashboard",


If you parse it with get_dict_from_params, I think you will need to use quats: type=["Lakehouse","Notebook"]

aviatco · 2026-03-15T13:05:06Z

src/fabric_cli/parsers/fab_find_parser.py

+        "-l",
+        "--long",
+        action="store_true",
+        help="Show detailed output. Optional",


required=False ?

aviatco · 2026-03-15T13:07:01Z

issue-172.md

@@ -0,0 +1,312 @@
+### Use Case / Problem


what is this file?
should be removed?

Sorry it's just the draft of the issue itself. I'll remove it.

aviatco · 2026-03-15T13:08:14Z

tests/test_commands/find/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.


remove and place the test_find directly under test_command

aviatco · 2026-03-15T13:11:21Z

tests/test_commands/find/test_find.py

+        assert payload["filter"] == "(Type ne 'Dashboard' and Type ne 'Datamart')"
+
+
+class TestParseTypeParam:


you should create e2e tests that call find command and record the tests and validate all different scenarios instead of those unit tests.

aviatco · 2026-03-15T13:17:55Z

Please update the description:

fab find "monthly" --type Report Warehouse - should be list

fab find "dashboard" --max-items 10 - flag doesnt exist

fab find --next-token "eyJTa2lwIjoy..." - flag doesnt exist

aviatco · 2026-03-15T13:22:43Z

src/fabric_cli/commands/find/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.


Please add documentation for this new command - under docs folder.
here you can find the guidelines how to rebuild it locally

This is just a draft of the issue I opened

Nadav Schachter added 21 commits February 9, 2026 17:51

feat(find): add --limit validation (1-1000)

d2cac8c

fix(find): correct print_output_format call for table display

30e34a5

feat(find): add key-value layout for --detailed flag

56f8a6b

refactor(find): change --detailed to -l/--long to match CLI convention

7c231bc

feat(find): hide empty keys in long output

fb64188

refactor(find): reorder long output fields (name, id, type, workspace…

30507c7

…, workspace_id, description)

feat(find): add blank line separator before results

a7e1f90

feat(find): add blank line before count message

16941b7

feat(find): add --continue flag for pagination

7f3bdb3

fix(find): fix --continue to not duplicate search/filter params

5fa2c6b

refactor(find): rename flags to --max-items and --next-token

d45eb13

feat(find): hide description column when all descriptions are empty

6dca122

fix(find): remove Scorecard from unsupported types (returned as Report)

f68abf3

fix(find): remove Dataflow from unsupported types (Gen2 CI/CD is sear…

d55a386

…chable)

docs(find): clarify Dataflow Gen1/Gen2 are not searchable

eb0bd4e

docs(find): add 'currently' to Dataflow note

c7d2c55

nadavs123 requested a review from a team as a code owner February 15, 2026 09:54

Nadav Schachter and others added 7 commits February 24, 2026 16:25

test(find): update tests for pagination and -P params refactor

3c60e96

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix(find): make -P type filter case-insensitive

88cf988

aviatco reviewed Mar 15, 2026

View reviewed changes

Delete issue-172.md

42b7432

This is just a draft of the issue I opened



		# All Fabric item types (from API spec, alphabetically sorted)
		ALL_ITEM_TYPES = [

		from fabric_cli.client.fab_api_types import ApiResponse


		def catalog_search(args: Namespace, payload: dict) -> ApiResponse:

		assert payload["filter"] == "(Type ne 'Dashboard' and Type ne 'Datamart')"


		class TestParseTypeParam:

Conversation

nadavs123 commented Feb 15, 2026

📥 Pull Request

Summary

Usage

Flags

Implementation details

Files added

Files modified

Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aviatco commented Mar 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants